---
{
	"title": "Tag filter",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "Filters through content and shows/hides content that match a certain tags.",
	"altLangPrefix": "tagfilter",
	"dateModified": "2022-09-10"
}
---

<div class="alert alert-warning">
	<h2>Unstable feature</h2>
	<p>To be used at <strong>your own risk</strong>. This feature described below can be removed in any subsequent minor/major release</p>
	<p><small><a href="https://wet-boew.github.io/wet-boew-documentation/decision/7.html">Learn more about the design decision around provisional features.</a></small></p>
	<p><small><a href="../../../docs/ref/provisional-en.html">Check other provisional features available.</a></small></p>
</div>

<span class="wb-prettify all-pre"></span>

<h2>Purpose</h2>
<p property="description">Filters through content and show/hide content that match certain tags.</p>

<h2>Use when</h2>
<p>You want to filter through an extensive list of items.</p>

<h2>Accessibility guidance</h2>
<p>The filter controls (checkboxes, radio buttons, dropdowns) <strong>must</strong> appear before the list of items they control.</p>

<h2>Working example</h2>
<p><a href="../../../demos/tagfilter/tagfilter-en.html">English example</a></p>
<p><a href="../../../demos/tagfilter/tagfilter-fr.html">French example</a></p>

<h2>How to implement</h2>
<h3>Wrap your section and tag your items.</h3>
<ol>
	<li>Wrap the whole section that is going to be filtered by tags in a <code>&lt;div class="wb-tagfilter provisional"></code>.</li>
	<li>Add the attribute <code>data-wb-tags</code> to each item or section that you want to control the visibility of, and define one or multiple tags as its value. Use a regular space between each tag, e.g., <code>data-wb-tags="tag1 tag2 tag3"</code>.</li>
</ol>
<h3>Identify your items wrapper</h3>
<p>Add the class <code>.wb-tagfilter-items</code> to the element wrapping your tagged items. For example:</p>
<pre><code>&lt;ul class="wb-tagfilter-items">
	&lt;li data-wb-tags="tag1">Item 1&lt;/li>
	&lt;li data-wb-tags="tag2">Item 2&lt;/li>
	&lt;li data-wb-tags="tag1">Item 3&lt;/li>
	&lt;li data-wb-tags="tag2">Item 4&lt;/li>
	&lt;li data-wb-tags="tag1">Item 5&lt;/li>
	...
&lt;/ul></code></pre>

<h3>Add your filter controls</h3>
<h4>For checkboxes</h4>
<ol>
	<li>Create your checkbox. <strong>The attribute <code>name</code> is mandatory for checkboxes</strong>.</li>
	<li>Add the attribute <code>value</code> to the checkbox. Note: the value of this attribute must be the same as the tag added to the item(s) above in order to control it, e.g., <code>value="myTag"</code>.</li>
	<li>Add the CSS class <code>wb-tagfilter-ctrl</code> to the checkbox.</li>
</ol>
<p>Your final checkbox should look like this:</p>
<pre><code>&lt;input type="checkbox" name="myCheckboxGroup" class="wb-tagfilter-ctrl" value="myTag"></code></pre>

<h4>For radio buttons</h4>
<ol>
	<li>Create your radio button. <strong>The attribute <code>name</code> is mandatory for radio buttons</strong>.</li>
	<li>Add the attribute <code>value</code> to the radio button. Note: the value of this attribute must be the same as the tag added to the item(s) above in order to control it, e.g., <code>value="myTag"</code>.</li>
	<li>Add the CSS class <code>wb-tagfilter-ctrl</code> to the radio button.</li>
</ol>
<p>Your final radio button should look like this:</p>
<pre><code>&lt;input type="radio" name="myRadioGroup" class="wb-tagfilter-ctrl" value="myTag"></code></pre>

<h4>For dropdowns</h4>
<ol>
	<li>Create your dropdown with your default option. <strong>The attribute <code>name</code> is mandatory for dropdowns</strong>.</li>
	<li>Add the CSS class <code>wb-tagfilter-ctrl</code> to the dropdown.</li>
	<li>Add your other options and define the attribute <code>value</code>. Note: the value of this attribute must be the same as the tag added to the item(s) above in order to control it, e.g., <code>value="myTag"</code>.</li>
</ol>
<p>Your final dropdown should look like this:</p>
<pre><code>&lt;select name="myDropdown" class="wb-tagfilter-ctrl">
	&lt;option value="">All&lt;/option>
	&lt;option value="myTag">My tag&lt;/option>
	&lt;option value="myTag2">My tag 2&lt;/option>
	&lt;option value="myTag3">My tag 3&lt;/option>
&lt;/select></code></pre>
<p><strong>Note:</strong> add an empty <code>value</code> to your default option in order to show all items.</p>

<h4>For date range</h4>
<ol>
	<li>Create your input <code>type="date"</code> for the start or end date</li>
	<li>The attribute <code>name</code> is mandatory and must be either <code>startDate</code> or <code>endDate</code></li>
	<li>Add the CSS class <code>wb-tagfilter-ctrl</code> to the input.
		<p>Your final date inputs should look like this:</p>
		<pre><code>&lt;label for=&quot;dateRangeStart&quot;&gt;Start Date:&lt;/label&gt;
	&lt;input type=&quot;date&quot; id=&quot;dateRangeStart&quot; name=&quot;startDate&quot; class=&quot;wb-tagfilter-ctrl form-control&quot;&gt;
	&lt;label for=&quot;dateRangeEnd&quot;&gt;End Date:&lt;/label&gt;
	&lt;input type=&quot;date&quot; id=&quot;dateRangeEnd&quot; name=&quot;endDate&quot; class=&quot;wb-tagfilter-ctrl form-control&quot;&gt;</code></pre>
	</li>
	<li><p>Add a <code>&lt;time&gt;</code> element to the tagged item. The <code>datetime</code> attribute of the <code>&lt;time&gt;</code> element must contain the <strong>ISO date</strong> for the item. This is what the date range filter uses to match items.</p>
	<pre><code>&lt;li data-wb-tags=&quot;tag1 tag2&quot;&gt;
&lt;time datetime=&quot;2025-09-10&quot;&gt;Wednesday September 10th, 2025&lt;/time&gt;
...
	&lt;/li&gt;</code></pre>
	</li>
</ol>
<p>This allows the plugin to filter tagged items based on the datetime attribute of their  <code>&lt;time&gt;</code> elements. You can use either start date, end date, or both together.</p>

<h3>Add your no result element</h3>
<p>Optionally, you can add an element that will show when there are no item visible. Identify this element with the CSS class <code>wb-tagfilter-noresult</code>.</p>
<p>This element needs to be added <strong>directly</strong> after the items wrapper (<code>.wb-tagfilter-items</code>).</p>
<p>For example:</p>
<pre><code>&lt;ul class="wb-tagfilter-items">
	&lt;li data-wb-tags="tag1">Item 1&lt;/li>
	&lt;li data-wb-tags="tag2">Item 2&lt;/li>
	&lt;li data-wb-tags="tag1">Item 3&lt;/li>
	&lt;li data-wb-tags="tag2">Item 4&lt;/li>
	&lt;li data-wb-tags="tag1">Item 5&lt;/li>
	...
&lt;/ul>
&lt;div class="wb-tagilfter-noresult">
	&lt;p>No item match this combination of filters.&lt;/p>
&lt;/div></code></pre>

<h3>Essential component behavior</h3>
<ul>
	<li>By default, for every checkbox filter group, if no checkbox is selected, it has the same effect as if all checkboxes were selected.</li>
	<li>The behavior for multiple checkboxes in a group is to display items that have either of the tags selected (OR behavior), not show items that have all the tags selected (AND behavior).</li>
</ul>

<h3>Notes</h3>
<p>For semantic purposes, every logical group of filters should be wrapped by a <code>&lt;fieldset></code> element.</p>
